Co-Op v2.2

- Script: Jon Irons (jonirons@gmail.com)
- Thanks: D. Watts, A. Bolton, G. Smith

===Contents===
  - Changelog
  - Requirements
  - Introduction
  - Sharing items
  - Beacons
  - Following Other Players ("Slaving")
  - Display Extras
  - User Variables
  - Notes

===Changelog===

  - 2.2
    * Future-proofed script for engine versions higher than 1.0,
      whose bundled Lua lacks the math.mod function. Script is
      still compatible with version 0.20 and above.
    * Changed monster information to show the monster's type
      instead of index
    * Information for inactive monsters no longer shows a life
      total (since it's always -1)

  - 2.1
    * Fixed several inventory-related bugs
    * Added instructional icons a la Visual Mode Lua
    * Removed timed beacon teleport after revive
    * Can cycle through slave beacons while dead
    * Added annotations on overhead map for all players' beacons
    * Significant code cleanup, especially of the hud() function
    * Monster kill count from Co-op v1 added
    * You get 100% health if you revive in a level
      flagged for Rebellion
  - 2.0
    * Initial release in new Lua API

===Requirements===

  * Minimum Aleph One version: 0.20 (June 22 2008)
  * Number of players: 2+
  * Gather as: Co-operative game type

===Introduction===

Co-Op 2.1 is the continuation of my earlier Co-Op Lua script. Thanks to
many innovations in recent versions of Aleph One, Co-Op 2's code is
simpler and more functional. The Co-Op Lua script is meant to smooth the
rough edges out of Aleph One's default co-operative game type,
addressing complaints that have prevented many players from enjoying
such games.

===Sharing Items===

Primarily, players now share items as they pick them up, which enables
maps originally designed to support a single player (for example,
Marathon 2 and Infinity... or just about any other scenario) to provide
enough weapons and ammunition for co-op games.  When a player dies, he
does not drop his items on the ground. Instead, his inventory is
restored to him when he revives. This allows games to continue even if
someone dies in a pit of lava with a chip or a valuable stockpile of
stuff, and it speeds up gameplay in less dire situations. This feature
is automatic.

===Beacons===

Another feature is the beacon system. Co-Op 1.0 used a clumsier method
to catch revived players up to each other that created a lot of tricky
timing. Instead, Co-Op 2 lets you place beacons at any location you can
reach.

To set a beacon, switch to the overhead map and press the action key
(make sure no switches or doors are in the way, or you'll activate those
instead). The beacon has a physical appearance: it uses a scenery object
to represent itself in the level. It also appears on the overhead map as
a small dot with an annotation next to it of the owner's name. Under the
name is a display of the beacon's age, in case you want to know how
recently the player placed it.

To go your beacon, switch to the overhead map and press the
microphone button to do so.  This makes it hard to teleport accidentally
(or excessively), but it also lets you take advantage of the benefits of
beacons. Oh, and don't worry: the microphone (speaking with it) is
disabled on the overhead map.

===Following Other Players ("Slaving")===

A different way to use beacons is to "slave" your beacon to another
player. If you do this, transporting will take you to his beacon instead
of your own (but you can still set your beacon's position independently
in case others want to use it).

To become slaved to a beacon, look at the overhead map and use the
previous/next weapon controls to cycle through players.  Your Lua HUD
will show an "S" icon where the "B" icon used to be, followed by the
name of the player you're now following. If you want to go back to using
your own beacon, go to the overhead map again and cycle to your beacon
(the "B" icon will replace "S" once again).

You can also slave while you are still dead. Use the weapon cycle
controls the same way you would if you were looking at the overhead map.

Slaving beacons can be of great value; here's an example:

Irons and Ryoko are playing a Co-op game in Ryoko's new scenario. They
have split up and are accomplishing different tasks simultaneously;
they've decided to slave to each other's beacons. Ryoko runs into a
larger group of monsters than he can handle at the moment, so he
retreats to a safer place, puts down a beacon, and tells Irons to join
him. Irons gives Ryoko a hand, then tells him there's a 3x charger near
his own beacon, so Ryoko dies, goes there, and refills his energy.

Think of other uses!

===Display Extras===

The Lua HUD in Co-Op 1 had some interesting display extras (mainly
player statistics regarding monster kills and player deaths). I decided
those weren't useful enough to keep around, and instead took advantage
of a feature in the new Lua API. If you look at a player, you'll see an
eyeball icon at the top of your screen, followed by his name and
health. If you look at a monster, the text changes to the monster's
index and its health.

Monster information can be disabled before you join a co-op game. Simply
add "--M" to the end of your name and join up. Lua-displayed names (in
the HUD) will get rid of this extra text.

Version 2.1 reimplements the counters for monsters killed and monsters
remaining. The small Pfhor icon is next to these numbers; they are in
the format of "killed : remaining."

===User Variables===
In case you need to make some scenario-specific adjustments (for
example, the beacon scenery object is now a tiny blood splatter because
of changes in the Shapes file, or certain items must not be shared among
players), you can open the script with a text editor and adjust the
variables in the "user variables" section near the beginning of the
file.  They are well-commented. The Aleph One Scripter's Guide that
comes with Aleph One (docs/Lua.html) can help you with things like
object, sound, fader, etc. mnemonics.

===Notes===

There is a long-standing bug in Co-Op: it is possible that your game
will freeze at seemingly random moments. Some people have never
experienced this, and some are plagued by it. If my script is to blame,
it probably has something to do with sharing items and getting caught in
an infinite loop. Until I can fix this, save your games early and often,
just in case. And if you see a pattern in the times the game chooses to
freeze, let me know.
